---
sidebar_label: Remote relationships
sidebar_position: 11
description: Manage remote relationships with the Hasura schema/Metadata API
keywords:
  - hasura
  - docs
  - schema/Metadata API
  - API reference
  - remote joins
  - remote relationships
---

# Schema/Metadata API Reference: Remote Relationships (Deprecated)

:::caution Deprecation

In versions `v2.0.0` and above, the schema/Metadata API is deprecated in
favour of the [schema API](/api-reference/schema-api/index.mdx) and the
[Metadata API](/api-reference/metadata-api/index.mdx).

Though for backwards compatibility, the schema/Metadata APIs will
continue to function.

:::

## Introduction

Remote Relationships allow you to join tables with Remote Schemas.

## create_remote_relationship {#schema-metadata-create-remote-relationship}

`create_remote_relationship` is used to create a new remote relationship
with an existing Remote Schema.

```http
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
   "type":"create_remote_relationship",
   "args":{
      "name": "sample_remote_relationship",
      "table": "users",
      "hasura_fields": ["id"],
      "remote_schema": "my-remote-schema",
      "remote_field": {
        "messages": {
           "arguments": {
              "id":"$id"
           }
        }
      }
   }
}
```

### Args syntax {#schema-metadata-create-remote-relationship-syntax}

| Key           | Required | Schema                                                                                                                          | Description                                                                                                                                |
| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| name          | true     | [RemoteRelationshipName](/api-reference/syntax-defs.mdx#remoterelationshipname)                                                 | Name of the remote relationship                                                                                                            |
| table         | true     | [QualifiedTable](/api-reference/syntax-defs.mdx#qualifiedtable)                                                                 | Object with table name and schema                                                                                                          |
| hasura_fields | true     | \[[PGColumn](/api-reference/syntax-defs.mdx#pgcolumn) \| [ComputedFieldName](/api-reference/syntax-defs.mdx#computedfieldname)] | Column/Computed field(s) in the table that is used for joining with Remote Schema field. All join keys in `remote_field` must appear here. |
| remote_schema | true     | [RemoteSchemaName](/api-reference/syntax-defs.mdx#remoteschemaname)                                                             | Name of the Remote Schema to join with                                                                                                     |
| remote_field  | true     | [RemoteField](/api-reference/syntax-defs.mdx#remotefield)                                                                       | The schema tree ending at the field in Remote Schema which needs to be joined with.                                                        |

## update_remote_relationship {#schema-metadata-update-remote-relationship}

`update_remote_relationship` is used to update an existing remote relationship.

```http
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type": "update_remote_relationship",
  "args": {
     "name": "sample_remote_relationship",
     "table": "users",
     "hasura_fields": ["id"],
     "remote_schema": "my-remote-schema",
     "remote_field": {
       "posts": {
          "arguments": {
             "id": "$id",
             "likes": {
                "lte":"1000"
             }
          }
       }
     }
  }
}
```

### Args syntax {#schema-metadata-update-remote-relationship-syntax}

| Key           | Required | Schema                                                                          | Description                                                                                                                 |
| ------------- | -------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| name          | true     | [RemoteRelationshipName](/api-reference/syntax-defs.mdx#remoterelationshipname) | Name of the remote relationship                                                                                             |
| table         | true     | [QualifiedTable](/api-reference/syntax-defs.mdx#qualifiedtable)                 | Object with table name and schema                                                                                           |
| hasura_fields | true     | \[[PGColumn](/api-reference/syntax-defs.mdx#pgcolumn)\]                         | Column(s) in the table that is used for joining with Remote Schema field. All join keys in `remote_field` must appear here. |
| remote_schema | true     | [RemoteSchemaName](/api-reference/syntax-defs.mdx#remoteschemaname)             | Name of the Remote Schema to join with                                                                                      |
| remote_field  | true     | [RemoteField](/api-reference/syntax-defs.mdx#remotefield)                       | The schema tree ending at the field in Remote Schema which needs to be joined with.                                         |

## delete_remote_relationship {#schema-metadata-delete-remote-relationship}

`delete_remote_relationship` is used to delete an existing remote relationship.

```http
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type" : "delete_remote_relationship",
    "args" : {
       "table":{
          "name":"users",
          "schema":"public"
       },
       "name":"sample_remote_relationship"
    }
}
```

### Args syntax {#schema-metadata-delete-remote-relationship-syntax}

| Key   | Required | Schema                                                                          | Description                       |
| ----- | -------- | ------------------------------------------------------------------------------- | --------------------------------- |
| table | true     | [QualifiedTable](/api-reference/syntax-defs.mdx#qualifiedtable)                 | Object with table name and schema |
| name  | true     | [RemoteRelationshipName](/api-reference/syntax-defs.mdx#remoterelationshipname) | Name of the remote relationship   |
